Inside Macintosh: QuickDraw GX Objects /

Chapter 3 - Style Objects / Using Style Objects

Manipulating Style Object Properties

Once you have created a style object, you can customize some of its features using the techniques described in this section. However, most of the functions you use to set style properties are described in the chapters that discuss style objects in Inside Macintosh: QuickDraw GX Graphics and Inside Macintosh: QuickDraw GX Typography.

This section describes how to manipulate those properties of style objects that are independent of the type of shape the style is associated with. You can reset a style's properties back to their default values, you can determine the owner count, and you can get and set the tag list.

For manipulating style objects as a whole, see "Creating and Manipulating Style Objects" beginning on page 3-7.

Resetting a Style Object's Default Properties

When you create a new style object with the GXNewStyle function, QuickDraw GX creates a style object with default properties. If you have altered any of the style object's properties using functions described in this chapter or in Inside Macintosh: QuickDraw GX Graphics or Inside Macintosh: QuickDraw GX Typography, you can reset the properties back to their default values using the GXResetStyle function.

Calling GXResetStyle returns all of the style's graphic and typographic properties to their default values. It does not affect the style's owner count or tag list.

The GXResetStyle function is described on page 3-21.

Getting and Setting Style Attributes and Text Attributes

A style object has two separate properties, attributes and text attributes, that consist of flags that affect style behavior. The attributes property of a style object affects mostly graphic shapes. You retrieve and assign attribute values, such as pen width, with the GXGetStyleAttributes and GXSetStyleAttributes functions. These functions, and the style attributes themselves, are described in the geometric styles chapter of
Inside Macintosh: QuickDraw GX Graphics.

The text attributes property of a style object affects typographic shapes only. You
retrieve and assign text attribute values, such as vertical-text selection, with the GXGetStyleTextAttributes and GXSetStyleTextAttributes functions, respectively. These functions, and the text attributes themselves, are described in the typographic styles chapter of Inside Macintosh: QuickDraw GX Typography.

Manipulating a Style Object's Owner Count

The owner count of an object indicates the number of current references to that object. In general, QuickDraw GX manages owner counts for you. For example, when you create a new style object, QuickDraw GX sets the owner count of the new style to 1. When you assign an existing style object to a shape, QuickDraw GX increments the style's owner count to correspond to the new reference to the style contained in the shape object.

If you want to manage a style's owner count directly--for example, if you want to track object references that you place in your own data structures, or if you want to know whether a style object is shared--you can use the GXGetStyleOwners function to determine the owner count of a style, and the GXCloneStyle and GXDisposeStyle functions to change the owner count of a style. The GXCloneStyle function increments the style's owner count, and the GXDisposeStyle function decrements the style's owner count, freeing the memory used by the style if the owner count goes to 0.

The GXGetStyleOwners function is described on page 3-22.

The following subsections discuss two common owner-count problems and how to avoid them. The problems are discussed in terms of style objects, but they apply equally well to other shared objects.

Avoiding Excessive Owner Count

The following is one plausible, but incorrect, way to create a style object and assign it to (the style reference property of) a shape:

GXSetShapeStyle(myShape, GXNewStyle());

After the execution of this statement, the owner count of the just-created style object is 2, not 1; creating the style object initialized its owner count to 1, and assigning it to the shape incremented its owner count to 2. If you were unaware of that, and deleted the shape object with the statement

GXDisposeShape(myShape);

the owner count of the style object would be decremented to 1, and the style would be left allocated in the heap when it should have been deleted.

A better way to create and assign a style object is to allocate a variable and use it in the assignment:

myStyle = GXNewStyle();
GXSetShapeStyle(myShape, myStyle);

As before, the style object's owner count is now 2. When you are finished with the variable reference to the style object, you can dispose of it:

GXDisposeStyle(myStyle);

That decreases the style's owner count to 1. When you are finished with the shape object, dispose of it as before:

GXDisposeShape(myShape);

That decreases the style's owner count to 0, and the style object is deleted as intended.

Avoiding Insufficient Owner Count

The following is one plausible, but incorrect, way to temporarily assign a style object to a shape, referenced in this example by the variable myShape. These statements save the original style into a variable, create a new style object, and assign the new style to the shape:

gxStyle myOldStyle = GXGetShapeStyle(myShape);
gxStyle myNewStyle = GXNewStyle();
GXSetShapeStyle(myShape, myNewStyle);

The first statement does not increase the owner count of the style referenced by myOldStyle; no new object is created and no additional references to myShape exist
in any object. The second statement results in an owner count of 1 for the style referenced by myNewStyle. The third statement decrements the owner count of the
style referenced by myOldStyle, and increments the owner count of the style referenced by myNewStyle (from 1 to 2).

Now suppose that you manipulate the new style object, draw the shape, and then wish to dispose of the new style and reassign the original style object back to the shape. You might expect to make two statements like this:

GXDisposeStyle(myNewStyle);
GXSetShapeStyle(myShape, myOldStyle);

As you would expect, disposing of myNewStyle decrements the owner count of the new style object from 2 to 1, and calling GXSetShapeStyle further decrements the owner count of the new style from 1 to 0, so that QuickDraw GX can delete it. However, the original style object, referenced by myOldStyle, may have been deleted by the original call to GXSetShapeStyle (because its owner count may have gone to 0 as a result of the call). If it has, myOldStyle will be nil and the new call to GXSetShapeStyle will fail.

A better way to temporarily save and restore a style object is to clone the original style before assigning the new style, as follows:

gxStyle myOldStyle = GXGetShapeStyle(myShape);
gxStyle myNewStyle = GXNewStyle();
GXCloneStyle(myOldStyle);
GXSetShapeStyle(myShape, myNewStyle);

The result of these statements is (assuming no other references to the style objects) an owner count of 2 for both the original and new style objects. Then, when the time comes to restore the original style object to the shape, you can make these statements:

GXDisposeStyle(myNewStyle);
GXSetShapeStyle(myShape, myOldStyle);
GXDisposeStyle(myOldStyle);

The first statement decrements the owner count of the new style from 2 to 1; the second statement decrements it from 1 to 0. The second statement increments the owner count of the original style from 1 to 2, so the third statement is added to bring it back down to 1, its original value.

Getting and Setting a Style Object's Tag References

You can examine the list of references to tag objects currently associated with a style object using the GXGetStyleTags function. Once you create a tag object, you can attach it to a style object using the GXSetStyleTags function. You can attach as many tag objects as you like to a style object.

Tag objects and the basic functions for manipulating them are described in the chapter "Tag Objects" in this book. That chapter also lists the common tag types defined and reserved by Apple Computer, Inc.

The GXGetStyleTags function is described on page 3-22. The GXSetStyleTags function is described on page 3-24.